.TH std::basic_string::replace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_string::replace \- std::basic_string::replace

.SH Synopsis
   basic_string& replace( size_type pos,
   size_type count,                               \fB(1)\fP (constexpr since
                          const basic_string& str     C++20)
   );
   basic_string& replace( const_iterator first,
   const_iterator last,                           \fB(2)\fP (constexpr since
                          const basic_string& str     C++20)
   );
   basic_string& replace( size_type pos,
   size_type count,

                          const basic_string&                          \fI(until C++14)\fP
   str,

                          size_type pos2,
   size_type count2 );
   basic_string& replace( size_type pos,
   size_type count,
                                                                       \fI(since C++14)\fP
                          const basic_string&                          (constexpr since
   str,                                                                C++20)

                          size_type pos2,
   size_type count2 = npos );
   basic_string& replace( size_type pos,
   size_type count,                                   \fB(4)\fP              (constexpr since
                          const CharT* cstr,                           C++20)
   size_type count2 );
   basic_string& replace( const_iterator first,
   const_iterator last,                               \fB(5)\fP              (constexpr since
                          const CharT* cstr,                           C++20)
   size_type count2 );
   basic_string& replace( size_type pos,                               (constexpr since
   size_type count,                                   \fB(6)\fP              C++20)
                          const CharT* cstr );
   basic_string& replace( const_iterator first,                        (constexpr since
   const_iterator last,                               \fB(7)\fP              C++20)
                          const CharT* cstr );
   basic_string& replace( size_type pos,
   size_type count,                                   \fB(8)\fP              (constexpr since
                          size_type count2, CharT                      C++20)
   ch );
   basic_string& replace( const_iterator first,
   const_iterator last,                           \fB(3)\fP \fB(9)\fP              (constexpr since
                          size_type count2, CharT                      C++20)
   ch );
   template< class InputIt >

   basic_string& replace( const_iterator first,                        (constexpr since
   const_iterator last,                               \fB(10)\fP             C++20)

                          InputIt first2, InputIt
   last2 );
   basic_string& replace( const_iterator first,                        \fI(since C++11)\fP
   const_iterator last,                               \fB(11)\fP             (constexpr since
                                                                       C++20)
    std::initializer_list<CharT> ilist );
   template< class StringViewLike >

   basic_string& replace( size_type pos,                               \fI(since C++17)\fP
   size_type count,                                   \fB(12)\fP             (constexpr since
                                                                       C++20)
                          const StringViewLike& t
   );
   template< class StringViewLike >

   basic_string& replace( const_iterator first,                        \fI(since C++17)\fP
   const_iterator last,                               \fB(13)\fP             (constexpr since
                                                                       C++20)
                          const StringViewLike& t
   );
   template< class StringViewLike >

   basic_string& replace( size_type pos,
   size_type count,                                                    \fI(since C++17)\fP
                          const StringViewLike&       \fB(14)\fP             (constexpr since
   t,                                                                  C++20)

                          size_type pos2,
   size_type count2 = npos );

   Replaces the characters in the range [begin() + pos, begin() + std::min(pos + count,
   size())) or [first, last) with given characters.

   1,2) Those characters are replaced with str.
   3) Those characters are replaced with a substring [pos2, std::min(pos2 + count2,
   str.size())) of str.
   4,5) Those characters are replaced with the characters in the range [cstr, cstr +
   count2).
   If [cstr, cstr + count2) is not a valid range, the behavior is undefined.
   6,7) Those characters are replaced with the characters in the range [cstr, cstr +
   Traits::length(cstr)).
   8,9) Those characters are replaced with count2 copies of ch.
   10) Those characters are replaced with the characters in the range [first2, last2)
   as if by replace(first, last, basic_string(first2, last2, get_allocator())).
   11) Those characters are replaced with the characters in ilist.
   12,13) Implicitly converts t to a string view sv as if by
   std::basic_string_view<CharT, Traits> sv = t;, then those characters are replaced
   with the characters from sv.
   These overloads participate in overload resolution only if
   std::is_convertible_v<const StringViewLike&,
                         std::basic_string_view<CharT, Traits>> is true and
   std::is_convertible_v<const StringViewLike&, const CharT*> is false.
   14) Implicitly converts t to a string view sv as if by std::basic_string_view<CharT,
   Traits> sv = t;, then those characters are replaced with the characters from the
   subview sv.substr(pos2, count2).
   This overload participates in overload resolution only if
   std::is_convertible_v<const StringViewLike&,
                         std::basic_string_view<CharT, Traits>> is true and
   std::is_convertible_v<const StringViewLike&, const CharT*> is false.

   If [begin(), first) or [first, last) is not a valid range, the behavior is
   undefined.

.SH Parameters

   pos           - start of the substring that is going to be replaced
   count         - length of the substring that is going to be replaced
   first, last   - range of characters that is going to be replaced
   str           - string to use for replacement
   pos2          - start of the substring to replace with
   count2        - number of characters to replace with
   cstr          - pointer to the character string to use for replacement
   ch            - character value to use for replacement
   first2, last2 - range of characters to use for replacement
   ilist         - initializer list with the characters to use for replacement
   t             - object (convertible to std::basic_string_view) with the characters
                   to use for replacement
.SH Type requirements
   -
   InputIt must meet the requirements of LegacyInputIterator.

.SH Return value

   *this.

.SH Exceptions

   1) Throws std::out_of_range if pos > size().
   3) Throws std::out_of_range if pos > size() or pos2 > str.size().
   4,6,8) Throws std::out_of_range if pos > size().
   12,14) Throws std::out_of_range if pos > size().

   If the operation would result in size() > max_size(), throws std::length_error.

   If an exception is thrown for any reason, these functions have no effect (strong
   exception safety guarantee).

.SH Example

    This section is incomplete
    Reason: no example

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to      Behavior as published              Correct behavior
   LWG 847  C++98      there was no exception safety   added strong exception safety
                       guarantee                       guarantee
   LWG 1323 C++98      the types of first and last     changed to const_iterator
                       were iterator
   LWG 2946 C++17      overloads (12,13) caused        avoided by making them templates
                       ambiguity in some cases

.SH See also

   replace_with_range replaces specified portion of a string with a range of characters
   (C++23)            \fI(public member function)\fP
   regex_replace      replaces occurrences of a regular expression with formatted
   \fI(C++11)\fP            replacement text
                      \fI(function template)\fP
   replace            replaces all values satisfying specific criteria with another
   replace_if         value
                      \fI(function template)\fP

.SH Category:
     * Todo no example
